<@page title="Tutorial" keywords="tutorial">

<p>This chapter is a quick, practical, but rough introduction to FMPP.</p>

<@sect title="Step 1: Process a directory">

<p>The basic idea is that you have <@e>source root directory</@> and an <@e>output root directory</@>. The source root directory contains the files to process, and the output root directory will contain the processed files.  Processing the file either means that FMPP will execute the file as FreeMarker template, or that it will copy the file as is (in the case of image files, archive files, etc.). (In fact there are other seldom used processing modes as well, like <@a href="settings.html#xmlRendering">XML rendering</@a>.)</p>

<p>To see an example, go to the <@example 'qtour_step1' /> directory. Here we have a directory called <@c>src</@>:</p>

<p><@figure src="qtour_step1_src.png" alt="Quick tour step 1 src" /></p>

<p>Also, you will find <@c>config.fmpp</@c> in the <@c>qtour_step1</@c> directory. This file contains the settings for FMPP, and now contains this:</p>

<@prg>
recommendedDefaults: ${pp.version}
sourceRoot: src
outputRoot: out
</@prg>

<p>If you issue <@c>fmpp</@c> command from the command-line while you are in the <@c>qtour_step1</@> directory, then FMPP will process the <@c>src</@> directory and places the output into the <@c>out</@> directory. On the console you will see something like:</p>

<@prg>
Note: Using the config.fmpp in the working directory.
- Executing: index.html
- Copying: falcon.png
- Executing: subdir\something.html

*** DONE ***

2 executed + 1 copied = 3 processed
0 failed, 0 warning(s)
Time elapsed: 0.234 seconds
</@prg>

<p>and the newly created <@c>out</@> directory will contain exactly the same files and subdirectories as <@c>src</@>.

<p align="center"><@figure src="qtour_step1.png" alt="Quick tour step 1 diagram" /></p>

<p>The above messages suggest that the PNG file was copied, while the two HTML-s were executed:</p>
<ul>
  <li>"Copying" means that the file is copied as is, without changing even a bit compared to the original file (binary copy).
  <li>"Executing" means that the file is interpreted by FreeMarker as template file, and the content of the output file is generated by FreeMarker. Template files are plain text files that can contain special parts, which are instructions to FreeMarker. Since in this first example the HTML files don't contain any such special parts, the output files will be identical to the original HTML-s.
</ul>

</@sect>

<@sect title="Step 2: Pulling data from a data source">

<p>If you look into the two HTML-s of <@c>qtour_step1/src</@c>, you see that both contains this line:</p>

<@prg><body bgcolor="#FFFFE0" text="#000000"></@prg>

<p>Assume you want to store these colors in a single centralized place, so if you change them, all pages will change. For this, you have to tell FMPP what <@e>data</@> to expose for the templates. For now, tell FMPP to load data from a TDD file. A TDD file is a simple text file that stores name-value pairs. (It happens to be the same format that <@c>config.fmpp</@c> uses, but it's just accidental coincidence. You could load data from other type of data source in the same way.) If you go to the <@example 'qtour_step2'/> directory, you will find <@c>style.tdd</@> in <@c>src/data</@> that contains this:</p>

<@prg>
bgColor: #FFFFE0
textColor: #000000
</@prg>

<p>Both line in both HTML-s has been changed to:</p>

<@prg><#noparse>
<body bgcolor="${bgColor}" text="${textColor}">
</#noparse></@prg>

<p>The two <@c>${"$"}{<@r>...</@>}</@>-s are instructions to FreeMarker that insert the value of a variable. When I'm saying that FMPP exposes data for the templates, then it simply means that it creates variables for the templates, based on some data source. We tell FMPP to load data from <@c>data/style.tdd</@c> file before it starts to process the files, in the <@c>config.tdd</@c> of the <@c>qtour_step2</@c> directory:</p>

<@prg>
recommendedDefaults: ${pp.version}
sourceRoot: src
outputRoot: out
data: tdd(data/style.tdd)
</@prg>

<p>If you issue an <@c>fmpp</@c> command in the <@c>qtour_step2</@> directory, and look into the result in the <@c>out</@> directory, then you will see that the <@c>${"$"}{<@r>...</@>}</@>-s in the HTML files are replaced with the actual colors.</p>

<p align="center"><@figure src="qtour_step2.png" alt="Quick tour step 2 diagram" /></p>

<p>It is important that the <@c>data</@> directory was not copied into the output (the files in it were not "executed" or "copied"). This is because <@c>src/data</@> contains a file with name <@c>ignoredir.fmpp</@>, and the presence of this file instructs FMPP not to process the directory.</p>

</@sect>

<@sect title="Step 3: Even more data">

<p>You can use any number of data sources, not only a single file. In <@example 'qtour_step3'/> I have added one more data source: <@c>data/birds.csv</@c>. CSV is a primitive format often used to exchange data among spread sheet applications and other applications. <@c>bird.csv</@c> stores a table with "name", "description" and "favoriteFood" columns. I want to use the content of this table in the generated HTML pages later, so let load this table into variable <@c>birds</@c>, in <@c>config.fmpp</@c>:</p>

<@prg>
recommendedDefaults: ${pp.version}
sourceRoot: src
outputRoot: out
data: {
    tdd(data/style.tdd)
    birds: csv(data/birds.csv)
}
</@prg>

<p>Here FMPP creates variables for the templates from multiple data sources (<@c>data/style.tdd</@c>, <@c>data/birds.csv</@c>).</p>

<p>The <@c>index.html</@c> now contains some new lines, that fetch the data form the CSV file via the <@c>birds</@c> variable, and print a list from it. The <@c>&lt;#<@r>...</@>></@> tags are instructions to FreeMarker (see in the <@fma>FreeMarker Manual</@fma>):</p>

<@prg><#noparse>
<ul>
<#list birds as bird>
  <li>${bird.name?cap_first}: ${bird.description}
      Favorite food: ${bird.favoriteFood}
</#list>
</ul>
</#noparse></@prg>

<p>The output of the above template lines will be something like:</p>

<@prg>
  <ul>
    <li>Arctic-tern: Flies very long distances all years.
        Favorite food: sardine
    <li>House-sparrow: Everybody knowns it.
        Favorite food: sunflower
    <li>Sakeret: Great hunter of the sky.
        Favorite food: pigeon
  </ul>
</@prg>

<p>Note that the template uses <@c>birds</@c> variable independently of the actual file format (CSV) behind it. You could replace the CSV with whatever data source that can be interpreted as table (as a database table) and the templates could be the same, only the <@c>config.fmpp</@c> has to be adjusted. (However, FMPP supports only a few data source types out of the box yet, so maybe you have to write/obtain extension Java classes for it.)</p>

<p>You can find more information about data and data loading <@a href="overview.html#data">here</@a>.</p>

</@sect>

<@sect title="Step 4: Multiple output files from the same source file">

<p>Let's say you want to create separate HTML pages for each birds, rather than listing all information about them on the index page, and you want only link to those pages on <@c>index.html</@>. <@example 'qtour_step4'/> does this. The index page had trivial changes to generate the links. The interesting is that we have a new file, <@c>bird.html</@>. This single file is the template for all bird pages, and will generate a separate HTML file for each birds:</p>

<p align="center"><@figure src="qtour_step4.png" alt="Quick tour step 4 diagram" /></p>

<p>The <@c>bird.html</@c> looks as this:</p>

<@prg><#noparse>
<@pp.dropOutputFile />
<#list birds as bird>
<@pp.changeOutputFile name=bird.name+".html" />
<html>
<head>  
  <title>${bird.name?cap_first}</title>
</head>  
<body bgcolor="${bgColor}" text="${textColor}">
  <h1>${bird.name?cap_first}</h1>
  
  <p>${bird.description}</p>

  <p><b>Favorite food:</b> ${bird.favoriteFood}</p>
</body>
</html>
</#list>
</#noparse></@prg>

<p>The <@c>&lt;@<@r>...</@>></@> tags are instructions to FreeMarker (see the <@fma>FreeMarker Manual</@fma>). The <@a href='pphash.html'><@e>pp variable</@></@a> is defined by FMPP, and is always there, automatically. It stores the built-in variables of FMPP, e.g. directives as <@c>dropOutputFile</@> above. <@c>&lt;@pp.dropOutputFile /></@> instructs FMPP to drop the current output file, so we will not have <@c>bird.html</@> in the output directory. <@c>&lt;@pp.changeOutputFile <@r>...</@r>/></@> instructs FMPP to start a new output file with the given name. So <@c>bird.html</@c> will produce 3 output files (one output file for each row of the table): <@c>arctic-tern.html</@c>, <@c>house-sparrow.html</@c>, and <@c>sakeret.html</@c>.</p>

</@sect>

</@page>